# Snow CLI User Guide - LSP Configuration and Usage

Welcome to Snow CLI! Agentic coding in your terminal.

## What is LSP

LSP (Language Server Protocol) is a standard protocol that enables a "language server" to provide capabilities to editors/tools, such as:

- Go to Definition
- Document Symbols / Outline
- Hover
- References
- Completion

## How Snow CLI uses LSP

Snow CLI will try to use LSP first for certain code-search capabilities. If LSP is unavailable or times out, it automatically falls back to regex/text-based search (so it won’t block usage).

Currently, LSP mainly enhances these built-in tools:

- `ace-search` (action=`find_definition`): prefers LSP "go to definition"; falls back to regex search on failure
- `ace-search` (action=`file_outline`): prefers LSP `documentSymbol`; falls back to regex search on failure

Notes:

- LSP calls have an internal timeout (default: 3 seconds). Large projects or cold-starting language servers may exceed this timeout and trigger fallback.
- Some servers (e.g., OmniSharp) strongly depend on accurate cursor position; it’s recommended to provide `contextFile + line + column` when calling tools (see below).

## Config file location and loading behavior

LSP config file path: `~/.snow/lsp-config.json`

Loading behavior:

1. When Snow CLI first needs LSP, it attempts to read `~/.snow/lsp-config.json`.
2. If the file does not exist, Snow CLI creates a default config file and uses the built-in default server list.
3. The config is cached in-process; restart Snow CLI after editing the file.

## Config file formats

Two formats are supported:

### Format 1 (recommended): with schemaVersion

```json
{
	"schemaVersion": 1,
	"servers": {
		"typescript": {
			"command": "typescript-language-server",
			"args": ["--stdio"],
			"fileExtensions": [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"],
			"installCommand": "npm install -g typescript-language-server typescript",
			"initializationOptions": {}
		}
	}
}
```

### Format 2 (compatible): servers mapping at the root

```json
{
	"typescript": {
		"command": "typescript-language-server",
		"args": ["--stdio"],
		"fileExtensions": [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]
	}
}
```

## Configuration fields

Each language server entry supports:

- `command` (required): command used to start the language server (must be resolvable from PATH)
- `args` (required): argument array
- `fileExtensions` (required): file extensions used to match files to this language
- `installCommand` (optional): an installation hint (Snow CLI will not run it automatically)
- `initializationOptions` (optional): forwarded to the LSP `initialize` request as `initializationOptions`

Important:

- The config uses an "all-or-nothing" validation strategy: if any server entry is missing required fields or has incorrect types, the entire config is treated as invalid and Snow CLI falls back to defaults.
- Language selection is based on file extensions (e.g., `.ts`, `.py`). Ensure your `fileExtensions` match your actual project files.

## Default built-in servers (written on first creation)

Default language keys (you can add/remove/modify):

- `typescript`: `typescript-language-server --stdio`
- `python`: `pylsp`
- `go`: `gopls`
- `rust`: `rust-analyzer`
- `java`: `jdtls`
- `csharp`: `csharp-ls`

Note: installation methods differ by platform. The main requirement is that `command` can be found from your terminal.

## Install and verify (Windows examples)

On Windows, Snow CLI uses `where <command>` to check whether a language server is installed and available on PATH.

You can verify manually:

```cmd
where typescript-language-server
where pylsp
where gopls
where rust-analyzer
where jdtls
where csharp-ls
```

Common installation examples:

1. TypeScript / JavaScript

```cmd
npm install -g typescript-language-server typescript
```

2. Python

```cmd
python -m pip install python-lsp-server
```

3. Go

```cmd
go install golang.org/x/tools/gopls@latest
```

If you don’t want to install LSP for a language, remove its entry (or remove its extensions). Snow CLI will fall back to regex search.

## Using LSP via ACE tools

### 1) Go to definition: `ace-search` (action=`find_definition`)

If you provide `contextFile`, Snow CLI will try LSP first; otherwise it uses regex search directly.

It’s recommended to pass cursor position:

- `line`: 0-indexed (first line is 0)
- `column`: 0-indexed (first column is 0)

Example: if your editor shows "Line 34, Column 7", you usually pass `line=33`, `column=6`.

### 2) File outline: `ace-search` (action=`file_outline`)

For extracting symbols from a single file, Snow CLI tries LSP `documentSymbol` first and falls back to regex search.

Tip:

- For large files/projects, start with `ace-search` (action=`file_outline`) to get a high-level map, then drill down.

## FAQ

### 1. I edited the config but nothing changed

- Make sure `~/.snow/lsp-config.json` is saved
- Restart Snow CLI (config is cached)

### 2. It always falls back to regex search

Common causes:

- Language server not installed or not on PATH (verify with `where <command>` on Windows)
- `fileExtensions` does not match your actual file suffixes
- Language server startup is slow and hits the 3s timeout

### 3. Inaccurate jumps / wrong results

- Provide `contextFile + line + column` when calling `ace-search` (action=`find_definition`)
- If `symbolName` appears multiple times in the file and you don’t pass position, Snow CLI will try the first occurrence, which may be inaccurate